Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 4 - Unicode Converter Reference / Unicode Converter Functions

Converting Between Unicode and Pascal Strings /

ConvertFromUnicodeToPString

Converts a Unicode string to Pascal in a Mac OS text encoding.

pascal OSStatus ConvertFromUnicodeToPString (
      UnicodeToTextInfo iUnicodeToTextInfo, 
      ByteCount iUnicodeLen, 
      ConstUniCharArrayPtr iUnicodeStr,
      Str255 oPascalStr);

iUnicodeToTextInfo

A Unicode converter object. You use the CreateUnicodeToTextInfo or CreateUnicodeToTextInfoByEncoding function to obtain the Unicode converter object for the conversion.

iUnicodeLen

The length in bytes of the Unicode string to be converted. This is the string your application provides in the iUnicodeStr parameter.

iUnicodeStr

A pointer to an array containing the Unicode string to be converted. For information on the Unicode character array, see Chapter 2, "Basic Text Types Reference."

oPascalStr

A buffer. On output, the converted Pascal string returned by the function.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) in the chapter "Basic Text Types Reference."

DISCUSSION

The ConvertFromUnicodeToPString function provides an easy and efficient way to convert a Unicode string to a Pascal string in a Mac OS text encoding without incurring the overhead associated with use of the function ConvertFromUnicodeToText (page 139) or ConvertFromUnicodeToScriptCodeRun (page 155).

If necessary, this function uses the loose mapping and fallback characters to map the text elements of the string. For fallback mappings, it uses the handler associated with the Unicode converter object.

The function returns a noErr result code if it has completely converted the Unicode string to the Pascal without using fallback characters. If the function returns the paramErr or kTECGlobalsUnavailableErr result codes, it did not convert the string.

If the function returns kTECTableFormatErr, the code encountered a table in an unknown format. The function did not completely convert the input string (and may not have converted any of it).

If the function returns kTECBufferBelowMinimumSizeErr, the output buffer was too small to allow conversion of any part of the input string. You need to increase the size of the output buffer and try again.

If the function returns the kTECUsedFallbacksStatus result code, the function has completely converted the string using one or more fallback characters.

If the function returns kTECOutputBufferFullErr, the output buffer was not big enough to completely convert the input. You can call the function again with another output buffer (or with the same output buffer, after copying its contents) to convert the remainder of the Unicode string.

If the function returns kTECPartialCharErr, the Unicode input string ended with an incomplete UTF-8 character, which can only happen for UTF-8 input. If you have subsequent input text available, you can append the unconverted input from this call to the beginning of the subsequent input text and call the function again.

If the function returns kTextUndefinedElementErr, the Unicode input string included a value that is undefined for the specified Unicode version. The function did not completely convert the input string, and fallback handling was not invoked. You can resume conversion from a point beyond the offending Unicode character, or take some other action.

If the function returns kTextIncompleteElementErr, then either the input string included a text element that is too long for the internal buffers, or the input string ended with a text element that may be incomplete. The latter case can happen only if you set the kUnicodeStringUnterminatedMask control flag. The function did not completely convert the input string, and fallback handling was not invoked.